Vibe Code and Deploy a Web Search AI Agent

┌─────────────────────────────────────────────────────────────────────┐
│                        USER INTERFACE (React)                        │
│                    "What are the latest AI news?"                    │
└──────────────────────────────────┬──────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      PYTHON BACKEND (FastAPI)                        │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────────────┐   │
│  │   Agent     │────▶│    LLM      │────▶│   Web Scraper       │   │
│  │ (Orchestrator)│    │  (Brain)    │     │ (BrightData SERP)   │   │
│  └─────────────┘     └─────────────┘     └─────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

mkdir deep-research-agent

I want to build a deep research AI agent that can answer questions by searching the web when needed.

The backend will be Python and the frontend will be React. Set up a clean project structure with:
- A services folder containing backend and frontend directories
- A Makefile for running common commands

Just create the folder structure for now.

Set up the Python backend in services/backend/.

I'll need:
- FastAPI for the web server
- An async HTTP client for making API calls
- Environment variable support
- Data validation

Create the requirements.txt with the necessary dependencies.

I need to store API keys for two services:
1. Zeabur AI Hub - an OpenAI-compatible LLM API (token: ZEABUR_API_TOKEN)
2. BrightData - a web scraping service (token: BRIGHTDATA_API_TOKEN)

Create a .env.example template and a .env file in the backend folder. Also include a ZEABUR_MODEL variable defaulting to gpt-4o-mini.

Also create a config.py file that uses pydantic-settings to load these environment variables.
IMPORTANT: For the CORS_ORIGINS field, use Union[List[str], str] type and add a @field_validator to parse comma-separated strings from .env into a list. This prevents parsing errors.

I need to communicate with Zeabur AI Hub, which is an OpenAI-compatible API.

Create a Python client in services/backend/llm.py that can:
- Send prompts and get responses
- Support conversation history (chat)
- Handle errors gracefully

The base URL is https://sfo1.aihub.zeabur.ai and it uses the standard OpenAI chat completions format. Use async/await for the HTTP calls.

I want to search the web using BrightData's SERP API.

Create a Python client in services/backend/scraper.py that:
- Takes a search query and returns Google search results
- Uses BrightData's API at https://api.brightdata.com/request
- Returns the parsed search results as JSON
- Handles errors without crashing

The API uses Bearer token authentication and needs these parameters:
- zone: "serp_api1"
- format: "json"
- data_format: "parsed_light"

IMPORTANT fixes to include:
1. Import and use urllib.parse.quote_plus to URL-encode the search query before building the Google search URL
2. Do NOT include a "language" parameter (BrightData rejects it)
3. BrightData returns response with structure {status_code, headers, body}. In _parse_search_results:
   - Check if data has a 'body' field and extract it
   - If body is a JSON string, parse it with json.loads()
   - Then look for 'organic' or 'organic_results' field for the search results

Now I need to build the AI agent that ties everything together.

Create services/backend/agent.py with an agent that:
1. Receives a user question
2. Uses the LLM to decide: "Does this need current information from the web?"
3. If yes: extracts search keywords, searches the web, then answers based on results
4. If no: answers directly from the LLM's knowledge

The agent should use the LLM client and web scraper we created. Add logging so I can see what the agent is doing at each step.

IMPORTANT: The answer() method should accept a use_web_search parameter (defaults to True). 
If use_web_search is False, skip the web search decision logic entirely and go straight to answering from LLM knowledge.

Create a FastAPI server in services/backend/main.py that:
- Has a POST /api/query endpoint that accepts a question and returns the agent's answer
- Has health check endpoints (GET / and GET /health)
- Loads the API keys from environment variables using the config.py settings
- Enables CORS so the frontend can call it

The request should be {"query": "...", "use_web_search": true} and response should be {"answer": "..."}.

IMPORTANT: Do NOT use the deprecated @app.on_event("startup") and @app.on_event("shutdown") decorators.
Instead, use the modern approach:
1. Import asynccontextmanager from contextlib
2. Create a lifespan async context manager function that handles startup and shutdown
3. Pass it to FastAPI as: app = FastAPI(lifespan=lifespan)

This prevents deprecation warnings.

Set up a React TypeScript frontend in services/frontend/ using Vite.

I'll need:
- React with TypeScript
- A markdown renderer (react-markdown with remark-gfm) to display formatted AI responses
- Environment variable support for the API URL

Create all the necessary config files (package.json, vite.config.ts, tsconfig.json, index.html) and the basic entry point files.

Create the main React component in services/frontend/src/App.tsx.

I want a simple chat interface where users can:
- Type a question in an input field
- Click "Ask" (or press Enter) to submit
- See a loading spinner while waiting
- See the AI's answer rendered as markdown (with tables, lists, links, etc.)
- See their recent query history (last 5 questions)

Handle errors gracefully and show error messages to the user.

Create modern, professional CSS styling for the frontend in services/frontend/src/App.css.

I want:
- A gradient background (dark blue to red tones)
- A clean white card in the center for the content
- Nice input field and button styling
- A spinning loader animation
- Good typography for the markdown content (headers, lists, tables, code blocks)
- Mobile responsive design

Make it look polished and professional.

Create a Makefile in the project root with commands to:
- Install all dependencies (both backend and frontend)
- Run the backend server
- Run the frontend dev server
- Run both together

Make it easy to get started with just "make install" and "make dev".

IMPORTANT: Add command aliases so both of these work:
- make run-backend AND make dev-backend (both do the same thing)
- make run-frontend AND make dev-frontend (both do the same thing)

This ensures consistency with different naming conventions.

Add a "Web Search" checkbox to the frontend that allows users to control whether the AI agent uses BrightData for web search.

Frontend changes (services/frontend/src/App.tsx):
- Add a checkbox state (useWebSearch) that defaults to true
- Add a checkbox UI above the input field with a clear label and description
- Send the checkbox state (use_web_search) in the API request body
- Update the loading message to show different text based on whether web search is enabled

Backend changes (services/backend/main.py):
- Update the QueryRequest model to accept an optional use_web_search boolean (defaults to True)
- Pass this parameter to the agent

Backend changes (services/backend/agent.py):
- Update the run() method to accept a use_web_search parameter
- If use_web_search is False, skip all web search logic and answer directly with the LLM
- Add logging to show whether web search is enabled or disabled

This feature lets users compare answers with and without web search.

deep-research-agent/
├── services/
│   ├── backend/
│   │   ├── .env
│   │   ├── .env.example
│   │   ├── agent.py
│   │   ├── llm.py
│   │   ├── main.py
│   │   ├── requirements.txt
│   │   └── scraper.py
│   └── frontend/
│       ├── src/
│       │   ├── App.css
│       │   ├── App.tsx
│       │   ├── index.css
│       │   └── main.tsx
│       ├── .env
│       ├── index.html
│       ├── package.json
│       ├── tsconfig.json
│       └── vite.config.ts
└── Makefile

# Install all dependencies
make install

# Or install separately:
cd services/backend && pip3 install -r requirements.txt
cd services/frontend && npm install

make dev-backend
# Or: cd services/backend && python3 main.py

✅ Environment loaded successfully
🔗 Connecting to Zeabur AI Hub: https://sfo1.aihub.zeabur.ai
🤖 Using model: gpt-4o-mini
🚀 Web Search AI Agent Server running on http://localhost:8000

make dev-frontend
# Or: cd services/frontend && npm run dev

VITE ready in XXX ms
➜  Local:   http://localhost:5173/

make install
make dev-backend  # Terminal 1
make dev-frontend # Terminal 2